home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 21 / Cream of the Crop 21 (Terry Blount) (October 1996).iso / editor / gsar110.zip / GSAR.TXT < prev    next >
Text File  |  1996-08-14  |  9KB  |  216 lines
  1.           gsar(1)                                                   gsar(1)
  2.  
  3.  
  4.           NAME
  5.                  gsar - General Search And Replace utility
  6.  
  7.  
  8.           SYNOPSIS
  9.                  gsar [options] [infile(s)] [outfile]
  10.  
  11.  
  12.           DESCRIPTION
  13.                  gsar (General Search And Replace) is a utility for search-
  14.                  ing for and --- optionally --- replacing strings  in  both
  15.                  text  and binary files. The search and replace strings can
  16.                  contain all kinds of characters (0--255), i.e. Ctrl  char-
  17.                  acters and extended ASCII as well.
  18.  
  19.                  The  algorithm  used  is  a  variation  of the Boyer-Moore
  20.                  search algorithm, modified to search binary  files.  As  a
  21.                  result of this, gsar is blindingly fast.
  22.  
  23.                  Opposed  to  line oriented search programs (like grep(1)),
  24.                  gsar will find all  matches  on  a  line.  Actually,  gsar
  25.                  doesn't  know  anything  about lines at all, all files and
  26.                  strings are treated as binary.
  27.  
  28.                  Gsar can search one or several  files  for  a  string  and
  29.                  report the occurrences. Gsar can read one file, search for
  30.                  a string, replace it with some other string, and create  a
  31.                  new file containing the changes. Gsar can perform a search
  32.                  and replace in multiple files, overwriting the  originals.
  33.                  Finally,  gsar can work as a filter, reading from standard
  34.                  input and writing to standard output.
  35.  
  36.  
  37.           OPTIONS
  38.                  All options can be concatenated into one single option i.e
  39.                  the command: gsar  -i -b -l is the same as gsar -ibl
  40.  
  41.                  An  option which takes an argument must be the last one in
  42.                  the concatenated option, since the rest of the  option  is
  43.                  taken as a possible argument.
  44.  
  45.                  Fields  enclosed  in  []  are optional, but mandatory when
  46.                  enclosed in <>.  Options are case sensitive i.e -b is  not
  47.                  the same as -B.
  48.  
  49.                  If no options are given, gsar just gives a brief help mes-
  50.                  sage.
  51.  
  52.              [infile(s)]
  53.                  Name(s) of input file(s) (wildcards allowed on  most  Unix
  54.                  shells  and  most DOS compilers). If the -F option is used
  55.                  input is taken from stdin.
  56.  
  57.              [outfile]
  58.                  Name of output file that is to contain  the  replacements.
  59.                  If  the  -F  option is used, transformed output is sent to
  60.                  stdout.
  61.  
  62.              -s<string>
  63.                  String to search for  in  file.  Ctrl  characters  can  be
  64.                  entered by using a `:' in the string followed by the ASCII
  65.                  value of the character. The value is entered using  a  `:'
  66.                  followed  by  three decimal digits or `:x' followed by two
  67.                  hex numbers.  To enter a colon (:) in the  search  pattern
  68.                  use `::'.  The string must follow directly after s.
  69.  
  70.                  Example:  To  search for the string :foo (`o' is 111 deci-
  71.                  mal, 6F in hex) use the search options:
  72.                    -s::foo or -s::fo:111 or -s::fo:x6F
  73.  
  74.                  If you want to search for a  string  with  spaces  in  it,
  75.                  under  MSDOS  surround  the expression with quotes.  Under
  76.                  Unix, use the mechanisms  your  shell  provides  (commonly
  77.                  quotes) to include space or other special characters.
  78.  
  79.                  Example: search for gsar is fast use:
  80.                    gsar "-sgsar is fast" foobar.txt
  81.  
  82.                  The  precompiled  MSDOS executable in the archive supports
  83.                  response files. Just put you gsar commands into a file and
  84.                  put  a  `@'  in  front of the filename on the gsar command
  85.                  line.
  86.  
  87.                  Example: file foobar.txt contains  -ssupercalifragilistic-
  88.                  expialidocus:
  89.                    gsar @foobar.txt poppins.txt
  90.  
  91.                  If response files are needed, most Unix shells will allow
  92.                    gsar `cat foobar.txt` poppins.txt
  93.  
  94.              -r[string]
  95.                  String  which  is to replace search string in file. Use -r
  96.                  to delete the search string from  the  file  i.e.  replace
  97.                  with  nothing.  Ctrl characters can be entered in the same
  98.                  way as in the search string. If this option is  left  out,
  99.                  gsar  only  performs  a  search.  The  string  must follow
  100.                  directly after r.
  101.  
  102.              -i
  103.                  Ignore case difference when comparing strings.  I.e.  foo-
  104.                  bar matches fooBAR.
  105.  
  106.              -B
  107.                  Just  display  the search & replace buffers, for test pur-
  108.                  poses.
  109.  
  110.              -f
  111.                  If the output file already exists this switch can be  used
  112.                  to force an overwrite of the existing output file.
  113.  
  114.              -o
  115.                  Search  and replace of multiple files, overwrite the input
  116.                  file(s). For each input  file,  gsar  creates  a  tempfile
  117.                  which contains the replacements and copies the tempfile to
  118.                  the original input file name. If no  matches  were  found,
  119.                  the input file stays the same. The tempfile is removed.
  120.  
  121.                  Example:
  122.                    gsar -s__ZTC__ -r__TURBOC__ -o foo.c bar.c bat.c
  123.                  The files foo.c, bar.c & bat.c are all changed.
  124.  
  125.              -c[n]
  126.                  Display  the  context  around a match in a textual manner.
  127.                  Undisplayable characters are displayed as a dot  (`.').  n
  128.                  is  optional  number  of  bytes  in context. n must follow
  129.                  directly after c.
  130.  
  131.              -x[n]
  132.                  Display the context around a match as a hexadecimal  dump.
  133.                  Undisplayable  characters  are displayed as a dot (`.'). n
  134.                  is optional number of bytes  in  context.  n  must  follow
  135.                  directly after x.
  136.  
  137.              -b
  138.                  Display the byte offset of the match in hex.
  139.  
  140.              -l
  141.                  Only list filename and number of matches if any (default).
  142.  
  143.              -h
  144.                  Suppress display of filename when  displaying  context  or
  145.                  byte offsets.
  146.  
  147.              -du
  148.                  Convert a DOS ASCII file to UNIX (strips carriage return).
  149.  
  150.              -ud
  151.                  Convert a UNIX ASCII file to DOS (adds carriage return).
  152.  
  153.              -F
  154.                  Filter mode, gsar takes it's input from  stdin  and  redi-
  155.                  rects  eventual  output  to stdout. All error messages are
  156.                  sent stderr.
  157.  
  158.              -G
  159.                  Display the GNU General Public Licence.
  160.  
  161.  
  162.           Examples
  163.                  Search for two spaces at the end of a line (DOS text)  and
  164.                  replace with just a carriage return overwriting the origi-
  165.                  nal files:
  166.  
  167.                    gsar  -s:x20:x20:x0d  -r:x0d  -o  foobar.txt  *.c
  168.  
  169.                  Convert a UNIX text file to  DOS  format  overwriting  the
  170.                  original file:
  171.  
  172.                    gsar  -ud  -o  unix.txt
  173.  
  174.                  Search  for  the  string  WATCOM  and replace with __ZTC__
  175.                  using gsar as a filter. Output  is  redirected  to  a  new
  176.                  file:
  177.  
  178.                    gsar  -sWATCOM  -r__ZTC__  -F  <  foo_w.c  >  foo_z.c
  179.  
  180.                  Display  textual  context  of the string error in the file
  181.                  gsar.exe disregarding case. With 40 bytes in the context:
  182.  
  183.                    gsar  -serror  -i  -c40  gsar.exe
  184.  
  185.                  Search for the string gnu in the file fsf and  replace  it
  186.                  with wildebeest, cre